                                   SlyVote
                                 Version 0.22 Beta
                           Release date: 2017-08-07

                                     by

                                Eric Oulashin
                                AKA Nightfox
                          Sysop of Digital Distortion
                  BBS internet address: digitaldistortionbbs.com
                     Alternate address: digdist.bbsindex.com
                        Email: eric.oulashin@gmail.com



Contents
========
1. Disclaimer
2. Introduction
3. Installation & Setup
4. Configuration file
5. Notes for sysops


1. Disclaimer
=============
I cannot guarantee that this script is 100% free of bugs.  However, I have
tested it, and I used it often during development, so I have some confidence
that there are no serious issues with it (at least, none that I have seen).


2. Introduction
===============
SlyVote is a voting booth door for Synchronet, which allows users to add and
vote on various topics with multiple-choice answers.  SlyVote makes use of the
voting capabilities in the Synchronet messagebase, which were added to
Synchronet 3.17.  Thus, SlyVote requires version 3.17 or higher of Synchronet,
along with the latest JavaScript files for Synchronet, such as the following:
- sbbsdefs.js
- text.js
- frame.js
- scrollbar.js
- DDLightbarMenu.js
- Possibly other JavaScript files

SlyVote requires an ANSI terminal, since SlyVote makes use of lightbar menus
which do cursor movement, etc.

Since SlyVote makes use of Synchronet's messagebase, SlyVote can be configured
to use one or more of your message sub-boards to work with.  If more than one
sub-board is specified, SlyVote will prompt the user which sub-board to use
when launching SlyVote.  You might want to create a separate local sub-board
just for poll voting topics, or perhaps multiple local sub-boards for poll
voting if you want to have separate categories of poll topics.  Also, it's
certainly possible to use SlyVote with a networked sub-board, as long as the
sub-board supports voting.  Message sub-boards that support voting would need
to be networked only with other Synchronet BBSes (Dove-Net is a common one,
although a few BBSes on Dove-Net are not Synchronet).  FidoNet networks and
other message networks that might not have Synchronet BBSes should not support
voting by default in Synchronet.

SlyVote's look and feel was initially based on DCT Vote, a voting booth door
which was available in the 1990s.

NOTE: SlyVote is currently in an early beta state and is not fully complete
yet.


3. Installation & Setup
=======================
First, ensure that you have an up-to-date Synchronet system running Synchronet
3.17 or higher, and ensure that your Synchronet JavaScript files (in
sbbs/exec/load) are up to date.  Before the official Synchronet 3.17 is/was
released, daily 3.17 beta builds can be downloaded from Vertrauen (the home
BBS of Synchronet).  See the section below titled "Updating Synchronet".

Setting up SlyVote
------------------
SlyVote is comprised of the following files:
1. SlyVote.js             The SlyVote script

2. SlyVote.cfg            The SlyVote configuration file

3. DDLightbarMenu.js      A JavaScript lightbar menu class used by SlyVote.
                          You do not need to edit or use this file directly.
                          You can keep this file in the SlyVote directory or
                          copy it to your sbbs/exec/load directory if it's
                          not already there.  This file has been added to
                          Synchronet's CVS source code repository in
                          sbbs/exec/load, so it may already be part of your
                          Synchronet setup if you have updated your JavaScript
                          files.

SlyVote.cfg is a plain text file, so it can be edited using any text editor.

Installing into Synchronet's external programs menu
---------------------------------------------------
This section assumes that SlyVote is installed in the directory
sbbs/xtrn/SlyVote.

To set up SlyVote in the Synchronet external programs menu:
1. Run SCFG
2. Choose "External Programs" and then "Online Programs (Doors)"
3. Choose a program section, and then add an entry that is set up as follows:
+[][?]----------------------------------------------------+
                          SlyVote                         
----------------------------------------------------------
 Name                       SlyVote                      
 Internal Code              SLYVOTE                      
 Start-up Directory         ../xtrn/SlyVote              
 Command Line               ?SlyVote.js                  
 Clean-up Command Line                                   
 Execution Cost             None                         
 Access Requirements        ANSI                         
 Execution Requirements                                  
 Multiple Concurrent Users  Yes                          
 Intercept I/O              No                           
 Native Executable          No                           
 Use Shell to Execute       No                           
 Modify User Data           No                           
 Execute on Event           No                           
 Pause After Execution      No                           
 BBS Drop File Type         None                         
 Place Drop File In         Node Directory               
+----------------------------------------------------------+


Installing into a command shell
-------------------------------
This section assumes that SlyVote is installed in the directory
sbbs/xtrn/SlyVote.

If you are unsure which command shell you are using, you are likely using
Synchronet's "default" command shell, which is contained in the files
default.src and default.bin in the synchronet/exec directory.  To modify the
default command shell, you'll need to open default.src with a text editor.
Then, you can add a menu command to run SlyVote as follows:
  exec "?../xtrn/SlyVote/SlyVote.js"

If you are using a JavaScript command shell, the process would be similar.  You
can add a menu command to run SlyVote as follows:
bbs.exec("?../xtrn/SlyVote/SlyVote.js");


Updating Synchronet
-------------------
SlyVote requires Synchronet 3.17 or higher, along with the latest Synchronet
JavaScript files.
Daily-built Windows beta binaries can be downloaded from this URL:
ftp://vert.synchro.net/main/SBBS/sbbs_dev.zip
Daily-built Linux x64 binaries can be downloaded here:
ftp://vert.synchro.net/main/SBBS/sbbs_dev.tgz
To update your JavaScript files, first download the sbbs_run archive - Either
one of the following:
With CRLF line endings: ftp://vert.synchro.net/main/SBBS/sbbs_run.zip
With CR line endings: ftp://vert.synchro.net/main/SBBS/sbbs_run.tgz
Then, extract the archive and copy the files from sbbs/exec/load into your
sbbs/exec/load directory.


4. Configuration file
=====================
The format of SlyVote.cfg is setting=value.  SlyVote.cfg supports the following
settings:

Setting                               Description
-------                               -----------
useAllAvailableSubBoards              Whether or not to use all available
                                      sub-boards where voting is enabled.
                                      Valid values are true and false.  This
                                      defaults to true.  If this is set to
                                      true, then any subBoardsCodes values
                                      in the configuration file (described
                                      below) will be ignored.

subBoardCodes                         A comma-separated list of internal
                                      sub-board codes specifying which
                                      sub-board or sub-boards to use for voting
                                      topics.  A single sub-board code can be
                                      specified if you only want to use one
                                      sub-board with SlyVote.  Also,
                                      subBoardCodes can appear multiple times
                                      in SlyVote.cfg, and all specified
                                      sub-boards will be used.  If any of the
                                      specified sub-board codes don't exist or
                                      refer to sub-boards that don't allow
                                      voting, then they will not be used.

5. Notes for sysops
===================
For sysops, polls can be deleted when viewing results from SlyVote.

SlyVote uses the following lines from Synchronet's text.dat file (located in
the sbbs/ctrl directory):
120 (CantPostOnSub)
501 (SelectItemHdr)
503 (SelectItemWhich)
759 (CantReadSub)
779 (VotingNotAllowed)
780 (VotedAlready)
781 (R_Voting)
787 (PollVoteNotice)